home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / NDK / NDK_3.5 / Documentation / Autodocs / resource.doc < prev    next >
Encoding:
C/C++ Source or Header  |  1999-10-29  |  7.9 KB  |  282 lines
  1. TABLE OF CONTENTS
  2.  
  3. resource.library/--background--
  4. resource.library/RL_CloseResource
  5. resource.library/RL_DisposeGroup
  6. resource.library/RL_DisposeObject
  7. resource.library/RL_GetObjectArray
  8. resource.library/RL_NewGroupA
  9. resource.library/RL_NewObjectA
  10. resource.library/RL_OpenResource
  11. resource.library/RL_SetResourceScreen
  12. resource.library/--background--               resource.library/--background--
  13.  
  14.    NAME
  15.     resource.library -- resource handling for BOOPSI classes
  16.  
  17.    DESCRIPTION
  18.     The resource.library offers an API to handle resource objects
  19.     (an object file created from ReActor or similar BOOPSI creator
  20.     tools). One can create BOOPSI objects and groups of BOOPSI
  21.     objects and resource tracking is completly done by 
  22.     resource.library.
  23.     
  24.     A resource object ist an AmigaDOS hunk object file that contains
  25.     data structures with all necessary informations for creating BOOPSI
  26.     objects. Special class informations allows to handle intuition
  27.     BOOPSI objects.
  28.     
  29.     Strings are automatically localized if needed. The resource
  30.     objects contains references to labels (for the locale string IDs)
  31.     and strings (for the default strings) which has to be linked with
  32.     symbol definitions from the application (a new catcomp version is
  33.     available to create assembler source files for those definitions).
  34.     
  35.     The default label for the resource object is _RCTResource (defined 
  36.     by ReActor). Use a statement like
  37.     
  38.         extern char RCTResource[];
  39.  
  40.     to access the resource object. The variable RCTResource has to be
  41.     used as the first argument to RL_OpenResource.
  42. resource.library/RL_CloseResource           resource.library/RL_CloseResource
  43.  
  44.    NAME
  45.     RL_CloseResource - close and free a resource object (V44)
  46.  
  47.    SYNOPSIS
  48.     RL_CloseResource(resource)
  49.                        A0
  50.  
  51.     VOID RL_CloseResource(RESOURCEFILE);
  52.  
  53.    FUNCTION
  54.     This routine closes a resource object that was previously opened with
  55.     RL_OpenResource. It frees all objects and object groups.
  56.  
  57.    INPUTS
  58.     resource -- a pointer to a resource. A value of NULL is acceptable
  59.                 which means a no-op.
  60.  
  61.    RESULTS
  62.     
  63.  
  64.    SEE ALSO
  65.     resource.library/RL_OpenResource
  66. resource.library/RL_DisposeGroup             resource.library/RL_DisposeGroup
  67.  
  68.    NAME
  69.     RL_DisposeGroup - dispose a group of objects (V44)
  70.  
  71.    SYNOPSIS
  72.     RL_DisposeGroup(resource, group)
  73.                      A0        A1
  74.  
  75.     VOID RL_DisposeGroup(RESOURCEFILE, Object **);
  76.  
  77.    FUNCTION
  78.     Disposes a group of objects that was allocated with RL_NewGroupA.
  79.     Never dispose a object from the group with RL_DisposeObject,
  80.     DisposeObject or DisposeDTObject.
  81.  
  82.    INPUTS
  83.     resource -- a pointer to a resource
  84.     group -- a pointer to an array of pointers to Object. A value of
  85.              NULL is acceptable which means a no-op.
  86.  
  87.    RESULTS
  88.     
  89.  
  90.    SEE ALSO
  91.     resource.library/RL_NewGroupA
  92. resource.library/RL_DisposeObject            resource.library/RL_DisposeObject
  93.  
  94.    NAME
  95.     RL_DisposeObject - dispose an object (V44)
  96.  
  97.    SYNOPSIS
  98.     RL_DisposeObject(resource, object)
  99.                       A0        A1
  100.  
  101.     VOID RL_DisposeObject(RESOURCEFILE, Object *);
  102.  
  103.    FUNCTION
  104.     Dispose an object that was allocated with RL_NewObjectA.
  105.  
  106.    INPUTS
  107.     resource -- a pointer to a resource
  108.     object -- a pointer to an Object. A value of NULL is acceptable which
  109.               means a no-op.
  110.  
  111.    RESULTS
  112.     
  113.  
  114.    SEE ALSO
  115.     resource.library/RL_NewObjectA
  116. resource.library/RL_GetObjectArray         resource.library/RL_GetObjectArray
  117.  
  118.    NAME
  119.     RL_GetObjectArray - get a pointer to a group of objects (V44)
  120.  
  121.    SYNOPSIS
  122.     group = RL_GetObjectArray(resource,object,id)
  123.      D0                        A0       A1    D0
  124.  
  125.     Object **RL_GetObjectArray(RESOURCEFILE, Object *, RESOURCEID);
  126.  
  127.    FUNCTION
  128.     If you allocated an Object using RL_NewObjectA a lot of additional
  129.     Objects and group of Objects may be allocated automatically. This
  130.     functions returns a pointer to a group of objects with a given group
  131.     ID.
  132.     
  133.     Never release the group with RL_DisposeGroupA. The group is released
  134.     automatically if the object is released
  135.  
  136.    INPUTS
  137.     resource -- a pointer to a resource
  138.     object -- a pointer to an Object
  139.     id -- a numeric id of a object group
  140.  
  141.    RESULTS
  142.     group -- a pointer to an array of pointers to Object
  143.  
  144.    SEE ALSO
  145.     resource.library/RL_NewObjectA
  146.     resource.library/RL_NewGroupA
  147. resource.library/RL_NewGroupA                   resource.library/RL_NewGroupA
  148.  
  149.    NAME
  150.     RL_NewGroupA - allocate a group of objects (V44)
  151.  
  152.    SYNOPSIS
  153.     group = RL_NewGroupA(resource,id,taglist)
  154.      D0                   A0      D0  A1
  155.  
  156.     Object **RL_NewGroupA(RESOURCEFILE, RESOURCEID, struct TagItem *);
  157.  
  158.    FUNCTION
  159.     The routine allocates a group of objects with a given numeric id.
  160.  
  161.    INPUTS
  162.     resource -- a pointer to a resource
  163.     id -- a numeric id
  164.     taglist -- a pointer to an array of TagItem. Currently no tags are
  165.                defined.
  166.  
  167.    RESULTS
  168.     group -- a pointer to an array of pointers to Object or NULL.
  169.  
  170.    SEE ALSO
  171.     resource.library/RL_DisposeGroup
  172.     resource.library/RL_GetObjectArray
  173. resource.library/RL_NewObjectA                 resource.library/RL_NewObjectA
  174.  
  175.    NAME
  176.     RL_NewObjectA - create a new object (V44)
  177.  
  178.    SYNOPSIS
  179.     object = RL_NewObjectA(resource,id,taglist)
  180.      D0                     A0      D0  A1
  181.  
  182.     Object *RL_NewObjectA(RESOURCEFILE, RESOURCEID, struct TagItem *);;
  183.  
  184.    FUNCTION
  185.     The routine creates a new object with a given numeric id.
  186.  
  187.    INPUTS
  188.     resource -- a pointer to a resource
  189.     id -- a numeric id
  190.     taglist -- a pointer to an array of TagItem. The tags are moved
  191.                forward to the call of NewObjectA, NewDTObjectA or
  192.                whatever is called to create the object
  193.  
  194.    RESULTS
  195.     object -- a pointer to an Object or NULL.
  196.  
  197.    SEE ALSO
  198.     intuition.library/NewObjectA
  199.     datatypes.library/NewDTObjectA
  200.     resource.library/RL_DisposeObject
  201. resource.library/RL_OpenResource             resource.library/RL_OpenResource
  202.  
  203.    NAME
  204.     RL_OpenResource - open a resource (V44)
  205.  
  206.    SYNOPSIS
  207.     resource = RL_OpenResource(resobject, screen, catalog)
  208.      D0                         A0         A1      A2
  209.  
  210.     RESOURCEFILE RL_OpenResource(APTR, struct Screen *, struct Catalog *);
  211.  
  212.    FUNCTION
  213.     This routine opens a resource object.
  214.     
  215.     If you give a NULL for the parameter screen do not call RL_NewObjectA
  216.     or RL_NewGroupA. You must first set a screen with 
  217.     RL_SetResourceScreen.
  218.  
  219.    INPUTS
  220.     resobject -- a pointer to a resource object
  221.     screen -- a pointer to a Screen. This may be NULL
  222.     catalog -- a pointer to a Catalog. This may be NULL
  223.  
  224.    RESULTS
  225.     resource -- a pointer to a resource or NULL
  226.  
  227.    EXAMPLE
  228.    
  229.     extern char RCTResource[];
  230.     struct Screen *screen;
  231.     
  232.     screen = LockPubScreen(NULL);
  233.     RESOURCEFILE resource = RL_OpenResource(RCTResource, screen, NULL);
  234.     if (resource)
  235.     {
  236.         /* create your objects here */
  237.     }
  238.     RL_CloseResource(resource);
  239.     UnlockPubScreen(NULL,screen);
  240.  
  241.    SEE ALSO
  242.     intuition.library/LockPubScreen
  243.     intuition.library/OpenScreenTagList
  244.     locale.library/OpenCatalogA
  245.     resource.library/RL_CloseResource
  246.     resource.library/RL_SetResourceScreen
  247. resource.library/RL_SetResourceScreen   resource.library/RL_SetResourceScreen
  248.  
  249.    NAME
  250.     RL_SetResourceScreen - sets or clears the screen (V44)
  251.  
  252.    SYNOPSIS
  253.     success = RL_SetResourceScreen(resource, screen)
  254.      D0                             A0        A1
  255.  
  256.     BOOL RL_SetResourceScreen(RESOURCEFILE, struct Screen *);
  257.  
  258.    FUNCTION
  259.     This routine sets or clears the screen of the resource. You must clear
  260.     the screen before you close or unlock it. You must set a valid screen
  261.     before you call NewObjectA or NewGroupA.
  262.     
  263.     Setting a new screen does not mean that the allocated objects are
  264.     automatically adapt to the new screen. This function only controls
  265.     the internal housekeeping of the screen (and related structures). If
  266.     you cannot adapt the allocated objects to a new screen (like setting
  267.     an attribute with the new screen value) you must dispose and
  268.     recreate them.
  269.     
  270.     If you set the same screen pointer as was before this function does
  271.     nothing but returns TRUE.
  272.  
  273.    INPUTS
  274.     resource -- a pointer to a resource
  275.     screen --  a pointer to a Screen or NULL
  276.  
  277.    RESULTS
  278.     success -- TRUE if the screen is successfully set or cleared.
  279.  
  280.    SEE ALSO
  281.     resource.library/RL_OpenResource
  282.